package org.examcity.util.beanconverter;

/**
 * Interface implemented by classes that convert instances of one class into another.
 * 
 * @author Antonio Gomes
 */
public interface Converter {

	/**
	 * Converts an object into a new object of another class.
	 * <p>
	 * The underlying strategy is completely up to the implementation. Even <code>null</code> values
	 * are valid for the parameter <code>sourceObject</code>. Implementations may also invoke other
	 * converters by invoking one of the methods available in {@link ConverterManager} obtained via
	 * the parameter <code>context</code>.
	 * 
	 * @param context Context shared by all converters in the same execution
	 * @param sourceClass Class of the source object. This may or may not be available.
	 * Implementations should consider this parameter if it is provided.
	 * @param sourceObject Template object. This value may be <code>null</code>
	 * @param targetClass Class of the target object
	 * @return clone object or <code>null</code> if applicable
	 * 
	 * @throws Exception if the convertion could not be performed due to any reason
	 */
	Object convert(ConverterContext context, Class<?> sourceClass, Object sourceObject,
			Class<?> targetClass) throws Exception;

}
